<!DOCTYPE html>
<html>
<head>
  <title>
    Decentralized Identifiers (DIDs) v0.13
  </title>
  <meta content='text/html; charset=utf-8' http-equiv='Content-Type'><!--
    === NOTA BENE ===
    For the three scripts below, if your spec resides on dev.w3 you can check them
    out in the same tree and use relative links so that they'll work offline.
   -->

  <script class='remove'
    src='https://www.w3.org/Tools/respec/respec-w3c-common'>
  </script><!--script src='./respec-w3c-common.js' class='remove'></script-->

  <script src="./common.js">
  </script>
  <script class="remove" type="text/javascript">
  var respecConfig = {
    // specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
    specStatus: "CG-DRAFT",

    // the specification's short name, as in http://www.w3.org/TR/short-name/
    shortName: "did",

    // subtitle
    subtitle: "Data Model and Syntaxes",

    // if you wish the publication date to be other than today, set this
    // publishDate:  "2009-08-06",

    // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
    // and its maturity status
    // previousPublishDate:  "1977-03-15",
    // previousMaturity:  "WD",

    // extend the bibliography entries
    localBiblio: ccg.localBiblio,

    github: "https://github.com/w3c-ccg/did-spec",
    includePermalinks: false,

    // if there a publicly available Editor's Draft, this is the link
    edDraftURI: "https://w3c-ccg.github.io/did-spec/",

    // if this is a LCWD, uncomment and set the end of its review period
    // lcEnd: "2009-08-05",

    // editors, add as many as you like
    // only "name" is required
    editors: [{
        name: "Drummond Reed",
        url: "https://www.linkedin.com/in/drummondreed/",
        company: "Evernym",
        companyURL: "https://evernym.com/"
      },
      {
        name: "Manu Sporny",
        url: "http://manu.sporny.org/",
        company: "Digital Bazaar",
        companyURL: "https://digitalbazaar.com/"
      },
      {
        name: "Markus Sabadello",
        url: "https://www.linkedin.com/in/markus-sabadello-353a0821",
        company: "Danube Tech",
        companyURL: "https://danubetech.com/"
      }
    ],

    // authors, add as many as you like.
    // This is optional, uncomment if you have authors as well as editors.
    // only "name" is required. Same format as editors.
    authors: [{
        name: "Drummond Reed",
        url: "https://www.linkedin.com/in/drummondreed/",
        company: "Evernym",
        companyURL: "https://evernym.com/"
      },
      {
        name: "Manu Sporny",
        url: "http://manu.sporny.org/",
        company: "Digital Bazaar",
        companyURL: "https://digitalbazaar.com/"
      },
      {
        name: "Dave Longley",
        url: "",
        company: "Digital Bazaar",
        companyURL: "https://digitalbazaar.com/"
      },
      {
        name: "Christopher Allen",
        url: "https://www.linkedin.com/in/christophera",
        company: "Blockchain Commons",
        companyURL: "https://www.BlockchainCommons.com"
      },
      {
        name: "Ryan Grant",
        url: "",
        company: "",
        companyURL: ""
      },
      {
        name: "Markus Sabadello",
        url: "https://www.linkedin.com/in/markus-sabadello-353a0821",
        company: "Danube Tech",
        companyURL: "https://danubetech.com/"
      }
    ],

    // name of the WG
    wg: "Credentials Community Group",

    // URI of the public WG page
    wgURI: "https://www.w3.org/community/credentials/",

    // name (with the @w3c.org) of the public mailing to which comments are due
    wgPublicList: "public-credentials",

    // URI of the patent status for this WG, for Rec-track documents
    // !!!! IMPORTANT !!!!
    // This is important for Rec-track documents, do not copy a patent URI from a random
    // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
    // Team Contact.
    wgPatentURI: "https://www.w3.org/community/about/agreements/cla/",
    maxTocLevel: 4,
    inlineCSS: true
  };
  </script>
  <style>
  pre .highlight {
    font-weight: bold;
    color: green;
  }
  </style>
</head>
<body>
  <section id='abstract'>
    <p>
Decentralized Identifiers (DIDs) are a new type of identifier for
verifiable, "self-sovereign" digital identity. DIDs are fully under the
control of the DID subject, independent from any centralized registry,
identity provider, or certificate authority. DIDs are URLs that relate
a DID subject to means for trustable interactions with that subject.
DIDs resolve to DID Documents — simple documents that describe how to
use that specific DID. Each DID Document may contain at least three
things: proof purposes, verification methods, and service endpoints.
Proof purposes are combined with verification methods to provide mechanisms
for proving things. For example, a DID Document can specify that a particular
verification method, such as a cryptographic public key or pseudonymous
biometric protocol, can be used to verify a proof that was created for the
purpose of authentication. Service endpoints enable trusted interactions with
the DID controller.
    </p>
    <p>
This document specifies a common data model, format, and operations
that all DIDs support.
    </p>
  </section>

  <section id='sotd'>
    <p>
Comments regarding this document are welcome. Please file issues
directly on <a href="https://github.com/w3c-ccg/did-spec/issues/">GitHub</a>, or send them
to <a href="mailto:public-credentials@w3.org">public-credentials@w3.org</a> (
<a href="mailto:public-credentials-request@w3.org?subject=subscribe">subscribe</a>,
<a href="https://lists.w3.org/Archives/Public/public-credentials/">archives</a>).
    </p>

    <p>
Portions of the work on this specification have been funded by the
United States Department of Homeland Security's Science and Technology
Directorate under contracts HSHQDC-16-R00012-H-SB2016-1-002 and
HSHQDC-17-C-00019. The content of this specification does not
necessarily reflect the position or the policy of the U.S. Government
and no official endorsement should be inferred.
    </p>

    <p>
Work on this specification has also been supported by the Rebooting the
Web of Trust community facilitated by Christopher Allen, Shannon
Appelcline, Kiara Robles, Brian Weller, Betty Dhamers, Kaliya Young,
Kim Hamilton Duffy, Manu Sporny, Drummond Reed, Joe Andrieu, and
Heather Vescent.
    </p>
  </section>

  <section class="informative">
    <h1>
Introduction
    </h1>

      <p>
Conventional <a href="https://en.wikipedia.org/wiki/Identity_management">identity
management</a> systems are based on centralized authorities such as
corporate <a href="https://en.wikipedia.org/wiki/Directory_service">directory
services</a>, <a href="https://en.wikipedia.org/wiki/Certificate_authority">certificate
authorities</a>, or <a href="https://en.wikipedia.org/wiki/Domain_name_registry">domain name
registries</a>. From the standpoint of cryptographic trust
verification, each of these centralized authorities serves as its own
<a href="https://en.wikipedia.org/wiki/Trust_anchor">root of
trust</a>. To make identity management work across these systems
requires implementing <a href="https://en.wikipedia.org/wiki/Federated_identity">federated identity
management</a>.
      </p>

      <p>
The emergence of distributed ledger technology (DLT), sometimes
referred to as blockchain technology, provides the opportunity for
fully <a>decentralized identity management</a>. In a decentralized
identity system, entities (in the sense of discrete identifiable units
such as—but not limited to—people and organisations) are free to use any
shared root of trust.
Globally distributed ledgers, decentralized P2P networks, or other systems
with similar capabilities, provide the means for managing a root of
trust with neither centralized authority nor a single point of
failure. In combination, DLTs and decentralized identity systems
enable any entity to create and manage their own identifiers on any
number of distributed, independent roots of trust.
      </p>

      <p>
Entities are identified by decentralized identifiers (DIDs), and
may authenticate via proofs (e.g., digital signatures,
privacy-preserving biometric protocols, etc.). DIDs point to DID
Documents. A DID Document contains a set of service endpoints for
interacting with the entity the DID identifies (aka the DID subject).
Following the dictums of
<a href="https://en.wikipedia.org/wiki/Privacy_by_design">Privacy by
Design</a>, any entity may have as many DIDs as necessary (and
corresponding DID Documents and service endpoints), to respect the
entity’s desired separation of identities, personas, and contexts.
      </p>

      <p>
DID methods are the mechanism by which a DID and its associated DID
Document are created, read, updated, and deactivated on a specific
distributed ledger or network. DID methods are defined using separate
DID method specifications.
      </p>

      <p>
This design eliminates dependence on centralized registries for
identifiers as well as centralized certificate authorities for key
management—the standard pattern in hierarchical <a href="https://en.wikipedia.org/wiki/Public_key_infrastructure">PKI (public
key infrastructure</a>). Because DIDs reside on a distributed ledger,
each entity may serve as its own root authority—an architecture
referred to as <a href="https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust/blob/master/final-documents/dpki.pdf">
DPKI (decentralized PKI)</a>.
      </p>

      <p>
Note that DID methods may also be developed for identifiers
registered in federated or centralized identity management systems.
For their part, all types of identifier systems may add support for
DIDs. This creates an interoperability bridge between the worlds of
centralized, federated, and decentralized identifiers.
      </p>

      <p>
The first purpose of this specification is to define the generic
DID scheme and a generic set of operations on DID documents that can be
implemented for any <a>Decentralized Identifier Registry</a>. The second
purpose of this specification is to
define the conformance requirements for a DID method
specification—a separate specification that defines a specific DID
scheme and specific set of DID document operations for a specific
<a>Decentralized Identifier Registry</a>.
      </p>

      <p class="note">
Conceptually, the relationship of this specification and a DID
method specification is similar to the relationship of the IETF
generic URI specification ([[RFC3986]]) and a specific URI scheme
          ([[IANA-URI-SCHEMES]] (such as the http: and https: schemes
specified in [[RFC7230]]). It is also similar to the relationship
of the IETF generic URN specification ([[RFC8141]]) and a specific URN
namespace definition (such as the UUID URN namespace defined in
[[RFC4122]]). The difference is that a DID method specification, in
addition to defining a specific DID scheme, must also specify the
methods for resolving and deactivating DIDs and writing DID documents on the
network for which it is written.
      </p>

      <p>
For a list of DID Methods and their corresponding specifications,
see the DID Method Registry [[DID-METHOD-REGISTRY]].
      </p>

  <section class="informative">
    <h2>
A Simple Example
    </h2>

    <p>
A DID is a simple text string that consists of three parts: 1) the URL scheme
identifier (<code>did</code>), 2) the identifier for the
DID Method, and 3) the DID Method-specific identifier.
    </p>

    <pre class="example nohighlight" title="A simple example of a Decentralized Identifier (DID)">
did:example:123456789abcdefghi
    </pre>

    <p>
The DID above resolves to a DID Document. A DID Document contains information
associated with the DID such as ways to cryptographically authenticate the
entity in control of the DID, as well as services that can be used to
interact with the entity.
    </p>

    <pre class="example nohighlight" title="Minimal self-managed DID Document">
{
  "@context": "https://w3id.org/did/v1",
  "id": "did:example:123456789abcdefghi",
  "authentication": [{
    <span class="comment">// used to authenticate as did:...fghi</span>
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],
  "service": [{
    <span class="comment">// used to retrieve Verifiable Credentials associated with the DID</span>
    "type": "VerifiableCredentialService",
    "serviceEndpoint": "https://example.com/vc/"
  }]
}
      </pre>
    </section>

    <section class="informative">
      <h2>
Design Goals
      </h2>

      <p>
Decentralized Identifiers are a component of larger systems, such as
the Verifiable Credentials ecosystem [[?VC-DATA-MODEL]], which have driven
the design goals for this specification. This section summarizes the
primary design goals for this specification.
      </p>

      <table class="simple">
        <thead>
          <tr>
            <th>
Goal
            </th>
            <th>
Description
            </th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>
Decentralization
            </td>
            <td>
Eliminate the requirement for
centralized authorities or single points of failure in
identifier management, including the registration of globally
unique identifiers, public verification keys, service
endpoints, and other metadata.
            </td>
          </tr>

          <tr>
            <td>
Control
            </td>
            <td>
Give entities, both human and
non-human, the power to directly control their digital
identifiers without the need to rely on external authorities.
            </td>
          </tr>

          <tr>
            <td>
Privacy
            </td>
            <td>
Enable entities to control the privacy
of their information, including minimal, selective, and
progressive disclosure of attributes or other data.
            </td>
          </tr>

          <tr>
            <td>
Security
            </td>
            <td>
Enable sufficient security for relying
parties to depend on DID Documents for their required level of
assurance.
            </td>
          </tr>

          <tr>
            <td>
Proof-based
            </td>
            <td>
Enable the DID subject to provide
cryptographic proof when interacting with other entities.
            </td>
          </tr>

          <tr>
            <td>
Discoverability
            </td>
            <td>
Make it possible for entities to
discover DIDs for other entities to learn more about or
interact with those entities.
            </td>
          </tr>

          <tr>
            <td>
Interoperability
            </td>
            <td>
Use interoperable standards so DID
infrastructure can make use of existing tools and software
libraries designed for interoperability.
            </td>
          </tr>

          <tr>
            <td>
Portability
            </td>
            <td>
Be system and network-independent and
enable entities to use their digital identifiers with any
system that supports DIDs and DID Methods.
            </td>
          </tr>

          <tr>
            <td>
Simplicity
            </td>
            <td>
Favor a reduced set of simple features in order to make the technology
easier to understand, implement, and deploy.
            </td>
          </tr>

          <tr>
            <td>
Extensibility
            </td>
            <td>
When possible, enable extensibility
provided it does not greatly hinder interoperability,
portability, or simplicity.
            </td>
          </tr>
        </tbody>
      </table>
    </section>
  </section>

  </section>

  <section class="informative">
    <h1>
Terminology
    </h1>

    <div data-include="terms.html" data-oninclude="restrictReferences">
    </div>

  </section>

  <section class="informative">
    <h1>
Data Model
    </h1>
    <p>
This section outlines the Decentralized Identifier data model concepts.
These are elaborated in <a href="#did-documents"></a>.
    </p>

    <section>
      <h2>
Document
      </h2>
    </section>

    <section>
      <h2>
Keys
      </h2>
    </section>

    <section>
      <h2>
Services
      </h2>
    </section>

  </section>

  <section>
    <h1>
Decentralized Identifiers (DIDs)
    </h1>

    <p>
The concept of a globally unique <a>decentralized identifier</a> is not
new; <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">Universally
Unique Identifiers</a> (UUIDs) were first developed in the 1980s and
later became a standard feature of the Open Software Foundation’s
<a href="https://en.wikipedia.org/wiki/Distributed_Computing_Environment">Distributed
Computing Environment</a>. UUIDs achieve global uniqueness without a
centralized registry service by using an algorithm that generates
128-bit values with sufficient entropy that the chance of collision are
infinitesimally small. UUIDs are formally specified in [[RFC4122]] as a
specific type of Unified Resource Name (URN).
    </p>

    <p>
A DID is similar to a UUID except: (a) like a URL, it can be resolved
or dereferenced to a standard resource describing the subject (a <a>DID
Document</a>—see Section <a href="#did-documents"></a>), and (b) unlike
a URL, the DID Document typically contains cryptographic material that
enables authentication of the DID subject.
    </p>

    <section>
      <h2>
Generic DID Syntax
      </h2>

      <p>
The generic <a>DID scheme</a> is a URI scheme conformant with
[[RFC3986]]. The DID scheme specializes only the scheme and
authority components of a DID URI—the <code>path-abempty</code>,
<code>query</code>, and <code>fragment</code> components are
identical to the ABNF rules defined
in [[RFC3986]].
      </p>

      <p class="note">
The term <a>DID</a> refers only to the URI
conforming to the <code>did</code> rule in the ABNF below. A
DID always identifies the DID subject. The term <a>DID URL</a>,
defined by the <code>did-url</code> rule,
refers to a URL that begins with a DID followed by one or more
additional components. A DID URL always identifies the resource to
be located.
      </p>

      <p>
The following is the ABNF definition using the syntax in [[RFC5234]]
which defines <code>ALPHA</code> and <code>DIGIT</code>. All other
rule names not defined in this ABNF are defined in [[RFC3986]].
      </p>

      <pre class="nohighlight">
did                = "did:" method-name ":" method-specific-id
method-name        = 1*method-char
method-char        = %x61-7A / DIGIT
method-specific-id = *idchar *( ":" *idchar )
idchar             = ALPHA / DIGIT / "." / "-" / "_"
did-url            = did *( ";" param ) path-abempty [ "?" query ]
                     [ "#" fragment ]
param              = param-name [ "=" param-value ]
param-name         = 1*param-char
param-value        = *param-char
param-char         = ALPHA / DIGIT / "." / "-" / "_" / ":" /
                     pct-encoded
</pre>

      <p class="issue" data-number="198">
The grammar currently allows an empty <code>method-specific-id</code>,
e.g. <code>did:example:</code> would be a valid DID that could identify
the DID method itself.
      </p>

    </section>

    <section>
      <h2>
Method-Specific Syntax
      </h2>

      <p>
A DID method specification MUST further restrict the generic DID
syntax by defining its own <code>method-name</code> and its own
<code>method-specific-id</code> syntax. See Section <a href="#did-methods"></a>.
      </p>
    </section>

    <section>
      <h2>
Generic DID Parameter Names
      </h2>

      <p>
DID URL syntax supports a simple, generalized format for parameters based on the
matrix parameter syntax ([[MATRIX-URIS]]).
The ABNF above does not specify any parameter names (the <code>param-name</code>
rule).
      </p>
      <p>
Some generic DID parameter names (e.g., for service selection) are completely
independent of any specific DID method and MUST always function the same way
for all DIDs.
Others (e.g., for versioning) MAY be supported by
certain DID methods, but MUST operate uniformly across those DID methods that
do support them.
      </p>
      <p>
Parameter names that are completely method-specific are covered in
<a href="#method-specific-did-parameter-names"></a>.
      </p>
      <p>
The following table defines a set of generic DID parameter names:
      </p>

      <table class="simple">
        <thead>
          <tr>
            <th>Generic DID Parameter Name</th>
            <th>Description</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>
<code>service</code>
            </td>
            <td>
Identifies a service from the DID Document by service id.
            </td>
          </tr>

        </tbody>
      </table>

      <p>
The exact processing rules for these parameters are specified in the DID
Resolution specification.
      </p>

      <p class="note">
Note that there may be additional parameters or options that are not part
of the DID URL but instead passed to a DID resolver "out of band", i.e.,
using a resolution protocol or some other mechanism. Such options could
for example control caching or the desired format of a resolution result.
This is similar to HTTP, where caching or result format are expressed as
HTTP headers rather than as part of an HTTP URL. The important distinction
is that DID parameters that are part of the DID URL specify what resource
is being identified, whereas DID resolver options that are not part of the
DID URL control how that resource is dereferenced.
      </p>
    </section>

    <section>
      <h2>
Method-Specific DID Parameter Names
      </h2>

      <p>
A DID method specification MAY specify additional method-specific parameter
names. A method-specific parameter name MUST be prefixed by the method name
as defined by the <code>method-name</code> rule.
      </p>

      <p>
For example, if the method <code>did:foo:</code> defines the parameter bar,
the parameter name must be <code>foo:bar</code>. An example DID URL using
this method and this method-specific parameter would be:
      </p>

      <p>
<code>did:foo:21tDAKCERh95uGgKbJNHYp;foo:bar=high</code>
      </p>

      <p class="issue" data-number="199">
Consider using kebab-case style instead of colon separator,
e.g. <code>foo-bar</code> instead of <code>foo:bar</code>.
      </p>

      <p>
A method-specific parameter name defined by one DID method MAY
be used by other DID methods. For example:
      </p>

      <p>
<code>did:example:21tDAKCERh95uGgKbJNHYp;foo:bar=low</code>
      </p>

      <p>
Method-specific parameter names MAY be combined with generic parameter
names in any order.
      </p>

      <p>
<code>did:example:21tDAKCERh95uGgKbJNHYp;service=agent;foo:bar=high</code>
      </p>

      <p>
Both DID method namespaces and method-specific parameter
namespaces may include colons, so they may be partitioned hierarchically
as defined by a DID method specification. Here is an example DID URL that
illustrates both:
      </p>

      <p>
<code>did:foo:baz:21tDAKCERh95uGgKbJNHYp;foo:baz:hex=b612</code>
      </p>
    </section>

      <p class="issue" data-number="200">
Review what exactly we want to say about method-specific parameters
defined by one method but used in a DID URL with a different method.
Also discuss hierarchical method namespaces in DID parameter names.
      </p>

    <section>
      <h2>
Path
      </h2>

      <p>
A generic <a>DID path</a> is identical to a URI path and MUST
conform to the <code>path-abempty</code> ABNF rule in [[RFC3986]]. A
DID path SHOULD be used to address resources available via a DID
service endpoint. See Section <a href="#service-endpoints"></a>.
      </p>

      <p>
A specific DID scheme MAY specify ABNF rules for DID paths that are
more restrictive than the generic rules in this section.
      </p>
      <pre class="example nohighlight">
did:example:123456/path
      </pre>
    </section>

    <section>
      <h2>
Query
      </h2>

      <p>
A generic <a>DID query</a> is identical to a URI query and MUST
conform to the <code>query</code> ABNF rule in [[RFC3986]]. A
DID query SHOULD be used to address resources available via a DID
service endpoint. See Section <a href="#service-endpoints"></a>.
      </p>

      <p>
A specific DID scheme MAY specify ABNF rules for DID queries that are
more restrictive than the generic rules in this section.
      </p>
      <pre class="example nohighlight">
did:example:123456?query=true
      </pre>
    </section>

    <section>
      <h2>
Fragment
      </h2>

      <p>
A generic <a>DID fragment</a> is identical to a URI
fragment and MUST conform to the <code>fragment</code> ABNF rule in
[[RFC3986]]. A DID fragment MUST be used only as a method-independent
reference into the DID Document to identify a component of a DID Document
(e.g. a unique key description). To resolve this reference, the complete
DID URL including the DID fragment MUST be used as the value of
the key for the target component in the DID Document object.
      </p>

      <p>
A specific DID scheme MAY specify ABNF rules for DID fragments that
are more restrictive than the generic rules in this section.
      </p>

      <p>
It is desirable that we enable tree-based processing of DIDs that include
DID fragments (which resolve directly within the DID document) to locate
metadata contained directly in the DID document or the service resource
given by the target URL without needing to rely on graph-based processing.
      </p>
      <p>
Implementations SHOULD NOT prevent the use of JSON pointers ([[RFC6901]]).
      </p>
      <pre class="example nohighlight">
did:example:123456#oidc
      </pre>
    </section>

    <section>
      <h2>
Normalization
      </h2>

      <p>
For the broadest interoperability, DID normalization should be as
simple and universal as possible. Therefore:
      </p>

      <ol start="1">
        <li>
The did: scheme name MUST be lowercase.
        </li>

        <li>
The method name MUST be lowercase.
        </li>

        <li>
Case sensitivity and normalization of the value of the
<code>method-specific-id</code> rule in Section <a href="#generic-did-syntax">
          </a> MUST be defined by the governing DID method specification.
        </li>
      </ol>
    </section>

    <section>
      <h2>
Persistence
      </h2>

      <p>
A DID MUST be persistent and immutable, i.e., bound to the subject once
and never changed (forever).
      </p>

      <p>
Ideally a DID would be a completely
abstract decentralized identifier (like a UUID) that could be bound
to multiple underlying <a>Decentralized Identifier Registries</a> over time,
thus maintaining its persistence independent of any particular system.
However registering the same identifier on multiple
<a>Decentralized Identifier Registries</a> introduces extremely hard entityship and
<a href="https://en.wikipedia.org/wiki/List_of_DNS_record_types%23SOA">start-of-authority</a>
(SOA) problems. It also greatly increases implementation complexity
for developers.
      </p>

      <p>
To avoid these issues, it is RECOMMENDED that <a>DID method</a>
specifications only produce DIDs and <a>DID methods</a> bound to strong,
stable <a>Decentralized Identifier Registries</a> capable of making the highest level of
commitment to persistence of the DID and DID method over time.
      </p>

      <p class="note">
Although not included in this version, future versions of this
specification may support a DID Document equivID property to
establish verifiable equivalence relations between DIDs
representing the same subject on multiple <a>Decentralized Identifier
Registries</a>. Such equivalence relations can produce the practical
equivalent of a single persistent abstract DID. See Future Work
        (Section <a href="#future-work"></a>).
      </p>
    </section>
  </section>

  <section>
    <h1>
DID Documents
    </h1>

    <p>
A DID points to a DID Document. DID Documents are the serialization of
the <a href="#data-model"></a>.
The following sections define the properties of the DID Document,
including whether these properties are required or optional.
    </p>

    <section>
      <h2>Contexts</h2>

        <p>
When two software systems need to exchange data, they must use terminology and
a protocol that both systems understand. As an analogy, consider how two
people communicate. Both people must use the same language and the words they
use must mean the same thing to each other. This specification uses the
<code>@context</code> property to express the context of a conversation.
        </p>

        <dl>
          <dt><dfn>@context</dfn></dt>
          <dd>
The value of the <code>@context</code> property MUST be one or more
<a>URIs</a>, where the value of the first <a>URI</a> is
<code>https://www.w3.org/2019/did/v1</code>. If more than one
<a>URI</a> is provided, the <a>URIs</a> MUST be interpreted as an ordered set.
It is RECOMMENDED that dereferencing the <a>URIs</a> results in a document
containing machine-readable information about the context.
          </dd>
        </dl>

      <p>
  DID Documents MUST include the <code>@context</code> property. The
  <a href="https://www.w3.org/TR/json-ld/#the-context">JSON-LD Context</a>
  is described in detail in the [[!JSON-LD]] specification. The rules for this
  statement are:
      </p>

      <ol start="1">
        <li>
A DID Document MUST have exactly one top-level context statement.
        </li>

        <li>
The key for this property MUST be <code>@context</code>.
        </li>

        <li>
The value of this key MUST be the URL for the generic DID context:
<code>https://w3id.org/did/v1</code>.
        </li>
      </ol>

      <p>
Example (using an example URL):
      </p>

      <pre class="example nohighlight">
{
  "@context": "https://w3id.org/did/v1"
}
</pre>
      <p>
DID method specifications MAY define their own JSON-LD contexts.
However it is NOT RECOMMENDED to define a new context unless
necessary to properly implement the method. Method-specific contexts
MUST NOT override the terms defined in the generic DID context.
      </p>
    </section>

    <section>
      <h2>
DID Subject
      </h2>

      <p>
The DID subject is the identifier that the DID Document is about,
i.e., it is the DID described by DID Document. The rules for a DID
subject are:
      </p>

      <ol start="1">
        <li>
A DID Document MUST have exactly one DID subject.
        </li>

        <li>
The key for this property MUST be id.
        </li>

        <li>
The value of this key MUST be a valid DID.
        </li>

        <li>
When this DID Document is registered with the target <a>Decentralized
Identifier Registry</a>, the registered DID MUST match this DID subject
value.
        </li>
      </ol>

      <p>
Example:
      </p>

      <pre class="example nohighlight">
{
  "id": "did:example:21tDAKCERh95uGgKbJNHYp"
}
</pre>
      <p class="note">
DID Method specifications MAY create intermediate representations of
a DID Document that do not contain the <code>id</code> key, such as
when a DID Resolver is performing resolution. However, the fully
resolved DID Document MUST contain a valid <code>id</code> property.
      </p>
    </section>
    <!-- section>
<h2>Delegates</h2>

<p class="issue">
The way that Delegates are handled is changing. The feature is still supported,
but via the `authorizationCapability` field rather than the more specialized
`guardian` field.

</p>

<p>

A delegate is an entity, such as a parent or aid organization, that creates and
maintains a DID Document for a dependent who is not in a position to hold
or control authentication credentials (e.g., cryptographic keys).

</p>

<p>

The rules for a delegate are:

</p>

<ol start="1">
<li>


A DID Document that includes an
<code>authentication</code> field
(Section <a href="#authentication"></a>) MAY list one or
more delegates via the <code>authorizationCapability</code> field.

</li>

<li>


A DID Document that does not include an
<code>authentication</code> MUST have a delegate.

</li>

<li>


The <code>authorizationCapability</code> field must contain a capability for the
delegate that includes <code>UpdateDidDocument</code> as the capability,
the DID of the delegate as the <code>entity</code>, and MAY include a
more specific set of <code>authentication</code>s that the
delegate MAY use to authenticate when updating the DID Document.

</li>

<li>


The delegate DID MUST resolve to a DID Document that has a
<code>authentication</code> property containing at least one value,
i.e., the delegate relationships must not be nested.

</li>
</ol>

<p>

Example:

</p>

<pre class="example nohighlight" title="Basic DID Document">
{
"@context": "https://w3id.org/did/v1",
"id": "did:example:123456789abcdefghi",
"authorizationCapability": [{
  // this entity is a delegate and may update any field in this
  // DID Document using any authentication mechanism understood
  // by the ledger
  "permission": "UpdateDidDocument",
  "entity": "did:example:zxyvwtrkpn987654321"
}],
"authentication": [{
  // this biometric can be used to authenticate as did:...fghi
  "type": "PseudonymousBiometricTemplate2017",
  "biometricService": "https://example.com/authenticate",
  "biometricTemplateShard": "Mjk4MzQyO...5Mzg0MDI5Mwo="
}],
"service": [{
  "type": "ExampleService",
  "serviceEndpoint": "https://example.com/endpoint/8377464"
}]
}
</pre>
</section -->

    <section>
      <h2>
Public Keys
      </h2>

      <p>
Public keys are used for digital signatures, encryption and other
cryptographic operations, which in turn are the basis for purposes
such as authentication (see Section <a href="#authentication"></a>)
or establishing secure communication with <a>service endpoints</a>
(see Section <a href="#service-endpoints"></a>). In addition, public
keys may play a role in authorization mechanisms of DID CRUD
operations (see Section <a href="#did-operations"></a>). This may be
defined by DID Method specifications.
      </p>

      <p>
If a public key does not exist in the DID Document, it MUST be
assumed the key has been revoked or is invalid. The DID Document MAY
contain revoked keys. A DID Document that contains a revoked key MUST
also contain or refer to the revocation information for the key (e.g.,
a revocation list). Each DID Method specification is expected to
detail how revocation is performed and tracked.
      </p>

      <p>
The rules for public keys are:
      </p>

      <ol start="1">
        <li>
A DID Document MAY include a <code>publicKey</code> property.
        </li>

        <li>
The value of the <code>publicKey</code> property MUST be an array of
public keys, and every public key property MUST be in the
<a href="https://w3c-ccg.github.io/ld-cryptosuite-registry">Linked Data
Cryptographic Suite Registry</a>.
        </li>

        <li>
Each public key MUST include <code>id</code> and <code>type</code>
properties, and exactly one value property. The array of public keys
SHOULD NOT contain duplicate entries with the same <code>id</code> and
different value properties with different formats.
        </li>

        <li>
Each public key MUST include a <code>controller</code> property, which
identifies the controller of the corresponding private key.
        </li>

        <li>
A registry of key types and formats is available in Appendix
<a href="#registries"></a>.
        </li>
      </ol>
      <p class="note">
        The following is a non-exhaustive list of public key
        properties used by the community:
        <code>publicKeyPem</code>, <code>publicKeyJwk</code>,
        <code>publicKeyHex</code>, <code>publicKeyBase64</code>,
        <code>publicKeyBase58</code>, <code>publicKeyMultibase</code>,
        <code>ethereumAddress</code>.
      </p>
      <p>
Example:
      </p>

      <pre class="example nohighlight" title="Various public keys">
{
  "@context": ["https://w3id.org/did/v1", "https://w3id.org/security/v1"],
  "id": "did:example:123456789abcdefghi",
  ...
  "publicKey": [{
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }, {
    "id": "did:example:123456789abcdefghi#keys-2",
    "type": "Ed25519VerificationKey2018",
    "controller": "did:example:pqrstuvwxyz0987654321",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }, {
    "id": "did:example:123456789abcdefghi#keys-3",
    "type": "Secp256k1VerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyHex": "02b97c30de767f084ce3080168ee293053ba33b235d7116a3263d29f1450936b71"
  }],
  ...
}
</pre>
      <p>
A key may be <em>embedded</em> or <em>referenced</em> in a <a>DID
Document</a>. For example, the <code>authentication</code> property
may refer to keys in both ways:
      </p>

      <pre class="example nohighlight" title="Various public keys">
{
...

  "authentication": [
    // this key is referenced, it may be used for more than one proof purpose
    "did:example:123456789abcdefghi#keys-1",
    // this key is embedded and may *only* be used for authentication
    {
      "id": "did:example:123456789abcdefghi#keys-2",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:example:123456789abcdefghi",
      "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],

...
}
</pre>
      <p>
The algorithm to use when processing a <code>publicKey</code>
property in a <a>DID Document</a> is:
      </p>

      <ol class="algorithm">
        <li>
Let <em>value</em> be the data associated with the
        <code>publicKey</code> property and initialize <em>result</em> to
        <code>null</code>.
        </li>

        <li>
If <em>value</em> is an object, the key material is embedded. Set
        <em>result</em> to <em>value</em>.
        </li>

        <li>
If <em>value</em> is a string, the key is included by reference.
Assume <em>value</em> is a URL.
          <ol>
            <li>
Dereference the URL and retrieve the <code>publicKey</code>
properties associated with the URL (e.g., process the
            <code>publicKey</code> property at the top-level of the
dereferenced document).
            </li>

            <li>
Iterate through each public key object.
              <ol>
                <li>
If the <code>id</code> property of the object matches
                <em>value</em>, set <em>result</em> to the object.
                </li>
              </ol>
            </li>
          </ol>
        </li>

        <li>
If <em>result</em> does not contain at least the <code>id</code>,
        <code>type</code>, and <code>controller</code> properties as well as any
mandatory public cryptographic material, as determined by the
        <em>result</em>'s <code>type</code> property, throw an error.
        </li>
      </ol>

      <p class="note">
While the <code>controller</code> field may seem redundant in some of the
examples above, keys may be expressed in a DID Document where the
controller is described in another DID Document. Linked Data Proof
libraries typically expect the <code>controller</code> field to always
exist and may throw an exception if it is missing. Furthermore, per
the requirement that DID Documents be interpretable as either a graph
or a tree, a default <code>controller</code> field cannot be inferred by
using a key's position in a tree.
      </p>

      <p class="note">
Caching and expiration of the keys in a DID Document is entirely the
responsibility of DID resolvers and other clients. See Section
<a href="#did-resolvers"></a>.
      </p>
    </section>

    <section>
      <h2>
Authentication
      </h2>

      <p>
Authentication is the mechanism by which a <a href="#did-subject">DID subject</a> can
cryptographically prove that they are associated with a DID.
See Section <a href="#binding-of-identity"></a>. Note
that Authentication is separate from Authorization because the subject
may wish to enable others to update their DID Document (for
example, to assist with key recovery as discussed in Section
<a href="#key-revocation-and-recovery"></a>) without enabling them to prove
control (and thus be able to impersonate the subject).
      </p>

      <p>
The rules for Authentication are:
      </p>

      <ol start="1">
        <li>
A DID Document MAY include an <code>authentication</code>
property.
        </li>

        <li>
The value of the <code>authentication</code> property should be
an array of verification methods.
        </li>

        <li>
Each verification method MAY be embedded or referenced. An example of
a verification method is a public key (see Section <a href="#public-keys"></a>).
        </li>
      </ol>

      <p>
Example:
      </p>

      <pre class="example nohighlight" title="Authentication field containing three verification methods">
{
  "@context": "https://w3id.org/did/v1",
  "id": "did:example:123456789abcdefghi",
  ...
  "authentication": [
    // this method can be used to authenticate as did:...fghi
    "did:example:123456789abcdefghi#keys-1",
    // this method can be used to authenticate as did:...fghi
    "did:example:123456789abcdefghi#biometric-1",
    // this method is *only* authorized for authentication, it may not
    // be used for any other proof purpose, so its full description is
    // embedded here rather than using only a reference
    {
      "id": "did:example:123456789abcdefghi#keys-2",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:example:123456789abcdefghi",
      "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],
  ...
}
</pre>
    </section>

    <section>
      <h2>
Authorization and Delegation
      </h2>

      <p>
Authorization is the mechanism used to state how operations may be
performed on behalf of the DID subject. Delegation is the
mechanism that the subject may use to authorize others to act
on their behalf. Note that Authorization is separate from
Authentication as explained in Section <a href="#authentication"></a>.
This is particularly important for key
recovery in the case of key loss, when the subject no longer has
access to their keys, or key compromise, where the controller’s trusted
third parties need to override malicious activity by an attacker. See
Section <a href="#security-considerations"></a>.
      </p>

      <p>
Each DID Method MUST define how authorization and delegation are
implemented, including any necessary cryptographic operations.
      </p>

      <p>
There are at least two suggested methods for implementing
Authorization and Delegation, which may be layered:
      </p>

      <ol>
        <li>
A <a>Decentralized Identifier Registry</a> could implement a coarse
grained <code>controller</code> pattern by enabling DID documents to
express the DID of another DID controller that controls it, or
additionally,
        </li>

        <li>
A <a>Decentralized Identifier Registry</a> could implement a
Capabilities-based approach that enables further fine-grained control
of authorization and delegation.
        </li>
      </ol>

      <p>
Example:
      </p>

      <pre class="example nohighlight" title="DID Document with a controller property">
{
  "@context": "https://w3id.org/did/v1",
  "id": "did:example:123456789abcdefghi",
  "controller": "did:example:bcehfew7h32f32h7af3",
  "service": [{
    <span class="comment">// used to retrieve Verifiable Credentials associated with the DID</span>
    "type": "VerifiableCredentialService",
    "serviceEndpoint": "https://example.com/vc/"
  }]
}
        </pre>
    </section>

    <section>
      <h2>
Service Endpoints
      </h2>

      <p>
In addition to publication of authentication and authorization
mechanisms, the other primary purpose of a DID Document is to enable
discovery of <a>service endpoints</a> for the subject. A service
endpoint may represent any type of service the subject wishes to
advertise, including decentralized identity management services for
further discovery, authentication, authorization, or interaction. The
rules for service endpoints are:
      </p>

      <ol start="1">
        <li>
A DID Document MAY include a <code>service</code> property.
        </li>

        <li>
The value of the <code>service</code> property should be an array
of service endpoints.
        </li>

        <li>
Each service endpoint must include <code>id</code>,
        <code>type</code>, and <code>serviceEndpoint</code> properties, and
MAY include additional properties.
        </li>

        <li>
The service endpoint protocol SHOULD be published in an open
standard specification.
        </li>

        <li>
The value of the <code>serviceEndpoint</code> property MUST be a
JSON-LD object or a valid URI conforming to [[RFC3986]] and
normalized according to the rules in section 6 of [[RFC3986]] and to
any normalization rules in its applicable URI scheme specification.
        </li>
      </ol>

      <p>
Example:
      </p>

      <pre class="example nohighlight" title="Various service endpoints">
{
  "service": [{
    "id": "did:example:123456789abcdefghi#openid",
    "type": "OpenIdConnectVersion1.0Service",
    "serviceEndpoint": "https://openid.example.com/"
  }, {
    "id": "did:example:123456789abcdefghi#vcr",
    "type": "CredentialRepositoryService",
    "serviceEndpoint": "https://repository.example.com/service/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#xdi",
    "type": "XdiService",
    "serviceEndpoint": "https://xdi.example.com/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#agent",
    "type": "AgentService",
    "serviceEndpoint": "https://agent.example.com/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#hub",
    "type": "HubService",
    "serviceEndpoint": "https://hub.example.com/.identity/did:example:0123456789abcdef/"
  }, {
    "id": "did:example:123456789abcdefghi#messages",
    "type": "MessagingService",
    "serviceEndpoint": "https://example.com/messages/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#inbox",
    "type": "SocialWebInboxService",
    "serviceEndpoint": "https://social.example.com/83hfh37dj",
    "description": "My public social inbox",
    "spamCost": {
      "amount": "0.50",
      "currency": "USD"
    }
  }, {
    "id": "did:example:123456789abcdefghi#authpush",
    "type": "DidAuthPushModeVersion1",
    "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefg"
  }]
}
</pre>
      <p>
See Sections <a href="#did-method-schemes"></a>
and <a href="#authentication"></a> for further security
considerations regarding authentication service endpoints.
      </p>
    </section>

    <section>
      <h2>
Created (Optional)
      </h2>

      <p>
Standard metadata for identifier records includes a timestamp of the
original creation. The rules for including a creation timestamp are:
      </p>

      <ol start="1">
        <li>
A DID Document MUST have zero or one property representing a
creation timestamp. It is RECOMMENDED to include this property.
        </li>

        <li>
The key for this property MUST be created.
        </li>

        <li>
The value of this key MUST be a valid XML datetime value as
defined in section 3.3.7 of <a href="https://www.w3.org/TR/xmlschema11-2/">W3C XML Schema Definition
Language (XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]].
        </li>

        <li>
This datetime value MUST be normalized to UTC 00:00 as indicated
by the trailing "Z".
        </li>

        <li>
Method specifications that rely on DLTs SHOULD require time
values that are after the known <a href="https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki">"median
time past" (defined in Bitcoin BIP 113)</a>, when the DLT supports
such a notion.
        </li>
      </ol>

      <p>
Example:
      </p>

      <pre class="example nohighlight">
{
  "created": "2002-10-10T17:00:00Z"
}
</pre>
    </section>

    <section>
      <h2>
Updated (Optional)
      </h2>

      <p>
Standard metadata for identifier records includes a timestamp of the
most recent change. The rules for including an updated timestamp are:
      </p>

      <ol start="1">
        <li>
A DID Document MUST have zero or one property representing an
updated timestamp. It is RECOMMENDED to include this property.
        </li>

        <li>
The key for this property MUST be updated.
        </li>

        <li>
The value of this key MUST follow the formatting rules (3, 4, 5)
from Section <a href="#created-optional"></a>.
        </li>
      </ol>

      <p>
Example:
      </p>

      <pre class="example nohighlight">
{
  "updated": "2016-10-17T02:41:00Z"
}
</pre>
    </section>

    <section>
      <h2>
Proof (Optional)
      </h2>

      <p>
A <code>proof</code> on a DID Document is cryptographic proof of the
integrity of the DID Document according to either:
      </p>

      <ol start="1">
        <li>
The subject as defined in Section <a href="#service-endpoints"></a>, or if not present:
        </li>

        <li>
The delegate as defined in section 4.3.
        </li>
      </ol>

      <p>
This proof is NOT proof of the binding between a DID and a DID
Document. See Section <a href="#binding-of-identity"></a>. The rules
for a proof are:
      </p>

      <ol start="1">
        <li>
A DID Document MAY have exactly one property representing a
proof.
        </li>

        <li>
The key for this property MUST be <code>proof</code>.
        </li>

        <li>
The value of this key MUST be a valid JSON-LD proof as defined by
<a href="https://w3c-dvcg.github.io/ld-signatures/">Linked Data
Proofs</a>.
        </li>
      </ol>

      <p>
Example:
      </p>

      <pre class="example nohighlight" title="A signature-based proof">
{
  "proof": {
    "type": "LinkedDataSignature2015",
    "created": "2016-02-08T16:02:20Z",
    "creator": "did:example:8uQhQMGzWxR8vw5P3UWH1ja#keys-1",
    "signatureValue": "QNB13Y7Q9...1tzjn4w=="
  }
}
</pre>
    </section>

    <section>
      <h2>
Extensibility
      </h2>

      <p>
One of the goals of the Decentralized Identifiers Data Model is to
enable permissionless innovation. This requires that the data model
is extensible in a number of different ways:
      </p>

      <ul>
        <li>
The requirement to model complex multi-entity relationships is
provided through the use of a graph-based data model.
        </li>

        <li>
The requirement to enable extending the machine-readable
vocabularies used to describe information in the data model &mdash;
without relying on a centralized system &mdash; is accomplished via
the use of [[LINKED-DATA]].
        </li>

        <li>
The requirement to support multiple types of cryptographic proof
formats is accomplished via the use of Linked Data Proofs
[[LD-PROOFS]], Linked Data Signatures [[LD-SIGNATURES]], and a
variety of signature suites.
        </li>

        <li>
The requirement to provide all of the extensibility mechanisms
outlined above in a data format that is popular among software
developers and web page authors is enabled via the use of
[[!JSON-LD]].
        </li>
      </ul>

      <p>
This approach to data modeling is often called an "open world
assumption", meaning that anyone can say anything about any other
thing. This approach often feels in conflict with building simple
and predictable software systems. Balancing extensibility with
program correctness is always more challenging with an open world
assumption than it is with closed software systems.
      </p>

      <p>
The rest of this section describes how both extensibility and program
correctness are achieved through a series of examples.
      </p>

      <p>
Let us assume that we start with the following <a>DID Document</a>:
      </p>

      <pre class="example nohighlight" title="A simple DID Document">
{
  "@context": "https://example.org/example-method/v1",
  "id": "did:example:123456789abcdefghi",
  "publicKey": [{ ... }],
  "authentication": [{ ... }],
  "service": [{ ... }]
}
      </pre>
      <p>
The contents of the <code>publicKey</code>,
        <code>authentication</code>, and <code>service</code> properties are
not important for the purposes of this section. What is important is
that the object above is a valid <a>DID Document</a>. Let's assume
that a developer wanted to extend the <a>DID Document</a> to express
an additional piece of information: the subject's public photo
stream.
      </p>

      <p>
The first thing that a developer would do is create a JSON-LD Context
containing the new term:
      </p>

      <pre class="example nohighlight" title="An example JSON-LD Context">
{
  "@context": {
    "PhotoStreamService": "https://example.com/vocab#PhotoStreamService"
  }
}
      </pre>
      <p>
Now that the JSON-LD Context has been created, the developer MUST
publish it somewhere that is accessible to any <a>DID Document</a>
processor. For this example, let us assume that the JSON-LD Context
above is published at the following URL:
        <code>did:example:contexts:987654321</code>. At this point, extending
the first example in this section is a simple matter of including the
context above and adding the new property to the <a>DID Document</a>.
      </p>

      <pre class="example nohighlight" title="A DID Document with a custom extension">
{
  "@context": "https://example.org/example-method/v1",
  "id": "did:example:123456789abcdefghi",
  "authentication": [ ... ],
  "service": [<span class="highlight">{
    "@context": "did:example:contexts:987654321",
    "id": "did:example:123456789abcdefghi#photos",
    "type": "PhotoStreamService",
    "serviceEndpoint": "https://example.org/photos/379283"
  }</span>]
}
      </pre>
      <p>
The examples so far have shown that it is easy to extend the
Decentralized Identifiers Data Model in a permissionless and
decentralized way. The mechanism also ensures that Decentralized
Identifiers created in this way prevent namespace conflicts and
semantic ambiguity.
      </p>

      <p>
An extensibility model that is this dynamic does increase
implementation burden. Software written for such a system will have
to determine if accepting <a>DID Document</a>s with extensions is
acceptable based on the risk profile of the application. Some
applications may choose to accept but ignore extensions, others may
choose to only accept certain extensions, while highly secure
environments may disallow extensions. These decisions are up to the
application developers and are specifically not the domain of this
specification.
      </p>

      <p>
Implementations MUST produce an error when an extension JSON-LD
Context overrides the expanded URL for a term specified in this
specification. To avoid the possibility of accidentally overriding
terms, developers are urged to scope their extensions. For example,
the following extension scopes the new
        <code>PhotoStreamService</code> term so that it may only be used
within the <code>service</code> property:
      </p>

      <pre class="example nohighlight" title="Scoping terms in a JSON-LD Context">
{
  "@context": {
    <span class="highlight">"service": {
      "@id": "https://w3id.org/did#service",
      "@context": {
        "PhotoStreamService": "https://example.com/vocab#PhotoStreamService"
      }
    }</span>
  }
}
      </pre>
      <p>
Developers are urged to ensure that extension JSON-LD Contexts are
highly available. Implementations that cannot fetch a context will
produce an error. Strategies for ensuring that extension JSON-LD
Contexts are always available include using content-addressed URLs
for contexts, bundling context documents with implementations, or
enabling aggressive caching of contexts.
      </p>
    </section>
  </section>

  <section>
    <h1>
DID Document Syntax
    </h1>
        <p>
A DID Document MUST be a single JSON object conforming to [[RFC8259]].
Many of the concepts in this document were introduced by example using the
JSON-LD syntax, a format for mapping JSON data into the RDF semantic graph model as defined by
[[!JSON-LD]]. This section formalizes how the data model (described in Sections
<a href="#data-model"></a> and <a href="#did-documents"></a>) is realized in JSON-LD.
        </p>
        <p>
Although syntactic mappings are provided for JSON and JSON-LD only, applications and
services can use any other data representation syntax, such as JXD (JSON XDI Data, a serialization format for
the <a href="http://docs.oasis-open.org/xdi/xdi-core/v1.0/csd01/xdi-core-v1.0-csd01.xml">
XDI graph model</a>), XML, YAML, or CBOR, that is capable of expressing the data model.
        </p>

      <section>
        <h3>JSON</h3>

        <p>
The data model as described in Section <a href="#data-model"></a> can be
encoded in Javascript Object Notation (JSON) [[RFC8259]] by mapping property
values to JSON types as follows:
        </p>

        <ul>
          <li>
Numeric values representable as IEEE754 SHOULD be represented as a Number type.
          </li>
          <li>
Boolean values SHOULD be represented as a Boolean type.
          </li>
          <li>
Sequence value SHOULD be represented as an Array type.
          </li>
          <li>
Unordered sets of values SHOULD be represented as an Array type.
          </li>
          <li>
Sets of properties SHOULD be represented as an Object type.
          </li>
          <li>
Empty values SHOULD be represented as a null value.
          </li>
          <li>
Other values MUST be represented as a String type.
          </li>
        </ul>
      </section>

    <section>
      <h2>
JSON-LD
      </h2>

      <p>
[[!JSON-LD]] is a JSON-based format used to serialize
<a href="http://www.w3.org/TR/ld-glossary/#linked-data">Linked Data</a>. The
syntax is designed to easily integrate into deployed systems already using
JSON, and provides a smooth upgrade path from JSON to JSON-LD. It is primarily
intended to be a way to use Linked Data in Web-based programming environments,
to build interoperable Web services, and to store Linked Data in JSON-based
storage engines.
      </p>

      <p>
JSON-LD is useful when extending the data model described in this
specification. Instances of the data model are encoded in JSON-LD in the same
way they are encoded in JSON (Section <a href="#json"></a>), with the addition
of the <code>@context</code> property. The
<a href="https://www.w3.org/TR/json-ld/#the-context">JSON-LD Context</a>
is described in detail in the [[!JSON-LD]] specification and its use is
elaborated on in Section <a href="#extensibility"></a>.
      </p>

      <p>
In general, the data model and syntaxes described in this document are
designed such that developers can copy and paste examples into their software systems. The design goal of
this approach is to provide a low barrier to entry while still ensuring global
interoperability between a heterogeneous set of software systems. This section
describes some of these approaches, which will likely go unnoticed by most
developers, but whose details will be of interest to implementers. The most
noteworthy syntactic sugars provided by JSON-LD are:
      </p>

      <ul>
        <li>
The <code>@id</code> and <code>@type</code> keywords are aliased to
<code>id</code> and <code>type</code> respectively, enabling developers to use
this specification as idiomatic JSON.
        </li>
        <li>
Data types, such as integers, dates, units of measure, and URLs, are
automatically typed to provide stronger type guarantees for use cases that
require them.
        </li>
        <li>
The <code>@protected</code> properties feature of JSON-LD 1.1 is used to ensure
that terms defined by this specification cannot be overridden. This means
that as long as the same <code>@context</code> declaration is made at the top
of a <a>DID document</a>, that interoperability is guaranteed between implementations
which use a JSON-LD processor and implementations which do not.
        </li>
      </ul>
    </section>
  </section>

  <section>
    <h1>
DID Methods
    </h1>

    <section>
      <h2>
DID Method Schemes
      </h2>

      <p>
A DID method specification MUST define exactly one specific DID
scheme identified by exactly one method name (the <code>method-name</code> rule in
Section <a href="#generic-did-syntax"></a>).
      </p>

      <p>
Since the method name is part of the DID, it SHOULD be as short as
practical. A method name of five characters or less is RECOMMENDED.
The method name MAY reflect the name of the <a>Decentralized Identifier
Registry</a> to which the DID method specification applies.
      </p>

      <p>
The DID method specification for the specific DID scheme MUST specify
how to generate the <code>method-specific-id</code> component of a DID. The
<code>method-specific-id</code> value MUST be able to be generated without the use
of a centralized registry service. The <code>method-specific-id</code> value SHOULD
be globally unique by itself. The DID as defined by the <code>did</code> rule
in Section <a href="#generic-did-syntax"></a> MUST be globally unique.
      </p>

      <p>
If needed, a specific DID scheme MAY define multiple specific
<code>method-specific-id</code> formats. It is RECOMMENDED that a specific DID
scheme define as few <code>method-specific-id</code> formats as possible.
      </p>
    </section>

    <section>
      <h2>
DID Operations
      </h2>

      <p>
To enable the full functionality of DIDs and DID Documents on a
particular <a>Decentralized Identifier Registry</a>, a
DID method specification MUST specify how each of the following
<a href="https://en.wikipedia.org/wiki/Create,_read,_update_and_delete">
CRUD</a> operations is performed by a client. Each operation MUST be
specified to the level of detail necessary to build and test
interoperable client implementations with the target system. Note that,
due to the specified contents of DID Documents, these operations can
effectively be used to perform all the operations required of a CKMS
      (cryptographic key management system), e.g.:
      </p>

      <ul>
        <li>
Key registration
        </li>

        <li>
Key replacement
        </li>

        <li>
Key rotation
        </li>

        <li>
Key recovery
        </li>

        <li>
Key expiration
        </li>
      </ul>

      <section>
        <h3>
Create
        </h3>

        <p>
The DID method specification MUST specify how a client creates a DID
and its associated DID Document on the <a>Decentralized Identifier Registry</a>, including all
cryptographic operations necessary to establish proof of control.
        </p>
      </section>

      <section>
        <h3>
Read/Verify
        </h3>

        <p>
The DID method specification MUST specify how a client uses a DID to
request a DID Document from the <a>Decentralized Identifier Registry</a>, including how the
client can verify the authenticity of the response.
        </p>
      </section>

      <section>
        <h3>
Update
        </h3>

        <p>
The DID method specification MUST specify how a client can update a
DID Document on the <a>Decentralized Identifier Registry</a>, including all cryptographic
operations necessary to establish proof of control.
        </p>
      </section>

      <section>
        <h3>
Deactivate
        </h3>

        <p>
Although a core feature of distributed ledgers is immutability, the
DID method specification MUST specify how a client can deactivate a DID
on the <a>Decentralized Identifier Registry</a>, including all cryptographic
operations necessary to establish proof of deactivation.
        </p>
      </section>
    </section>

    <section class="informative">
      <h2>
Unique DID Method Names
      </h2>
      <p>
The authors of a new DID method specification are
expected to use a method name that is unique among all DID method
names known to them at the time of publication.
      </p>
      <p>
Because there is no central authority for allocating or approving DID
method names, there is no way to know for certain if a particular DID method
name is unique. To help with this challenge, the
<a href="https://www.w3.org/community/credentials/">W3C Credentials Community
Group</a> maintains a non-authoritative list of known DID
method names and their associated specifications (see Appendix
<a href="#registries"></a>).
      </p>
      <p>
The [[DID-METHOD-REGISTRY]] is a tool for implementors to use when coming
to consensus on a new method name, as well as an informative reference for
software developers implementing <a href="#did-resolvers"></a> for different
DID methods.
The [[DID-METHOD-REGISTRY]] is not a definitive or official list of DID
methods. Nonetheless, adding DID method names to the [[DID-METHOD-REGISTRY]] is
encouraged so that other implementors and members of the community have a
place to see an overview of existing DID methods. The lightweight criteria for
inclusion are documented in the [[DID-METHOD-REGISTRY]].
      </p>
    </section>

  </section>

  <section>
    <h1>
DID Resolvers
    </h1>

    <p>
A DID resolver is a software component with an API designed to accept
requests for DID lookups and execute the corresponding DID method to
retrieve the authoritative DID Document. To be conformant with this
specification, a DID resolver:
    </p>

    <ol start="1">
      <li>
SHOULD validate that a DID is valid according to its DID method
specification, otherwise it should produce an error.
      </li>

      <li>
MUST conform to the requirements of the applicable DID method
specification when performing DID resolution operations.
      </li>

      <li>
SHOULD offer the service of verifying the integrity of the DID
Document if it is signed.
      </li>

      <li>
MAY offer the service of returning requested properties of the DID
Document.
      </li>
    </ol>
  </section>

  <section class="informative">
    <h1>
Security Considerations
    </h1>

    <p>
NOTE TO IMPLEMENTERS: During the Implementer’s Draft stage, this
section focuses on security topics that should be important in early
implementations. The editors are also seeking feedback on threats and
threat mitigations that should be reflected in this section or
elsewhere in the spec. As the root identifier records for decentralized
identifiers, DIDs and DID Documents are a vital component of
decentralized identity management. They are also the foundational
building blocks of DPKI (decentralized public key infrastructure) as an
augmentation to conventional X.509 certificates. As such, DIDs are
designed to operate under the general Internet threat model used by
many IETF standards. We assume uncompromised endpoints, but allow
messages to be read or corrupted on the network. Protecting against an
attack when a system is compromised requires external key-signing
hardware. See also Section <a href="#key-revocation-and-recovery"></a>
regarding key revocation and recovery. For their part, the DLTs hosting
DIDs and DID Documents have special security properties for preventing
active attacks. Their design uses public/private key cryptography to
allow operation on passively monitored networks without risking
compromise of private keys. This is what makes DID architecture and
decentralized identity possible.
    </p>

    <section>
      <h2>
Requirements of DID Method Specifications
      </h2>

      <ol start="1">
        <li>
DID method specifications MUST include their own Security
Considerations sections.
        </li>

        <li>
This section MUST consider all the requirements mentioned in
section 5 of [[RFC3552]] (page 27) for the DID operations defined in
the specification. In particular:
        </li>
      </ol>

      <p class="issue">
Discussions at Rebooting the Web of Trust 5 resulted in consensus to
move Authorization to DID Method specifications. It is currently
expected that there will be an attempt to create a generalized
authorization mechanism that is build on object capabilities.
      </p>

      <p>
At least the following forms of attack MUST be considered:
eavesdropping, replay, message insertion, deletion, modification, and
man-in-the-middle. Potential denial of service attacks MUST be
identified as well. If the protocol incorporates cryptographic
protection mechanisms, it should be clearly indicated which portions
of the data are protected and what the protections are (i.e.,
integrity only, confidentiality, and/or endpoint authentication,
etc.). Some indication should also be given to what sorts of attacks
the cryptographic protection is susceptible. Data which should be
held secret (keying material, random seeds, etc.) should be clearly
labeled. If the technology involves authentication, particularly
user-host authentication, the security of the authentication method
MUST be clearly specified.
      </p>

      <ol start="3">
        <li>
This section MUST also discuss, per Section 5 of [[RFC3552]],
residual risks (such as the risks from compromise in a related
protocol, incorrect implementation, or cipher) after threat
mitigation has been deployed.
        </li>

        <li>
This section MUST provide integrity protection and update
authentication for all operations required by
Section <a href="#did-operations"></a>.
        </li>

        <li>
Where DID methods make use of peer-to-peer computing resources
        (such as with all known DLTs), the expected burdens of those
resources SHOULD be discussed in relation to denial of service.
        </li>

        <li>
Method-specific endpoint authentication MUST be discussed. Where
DID methods make use of DLTs with varying network topology, sometimes
offered as "light node" or "<a href="https://en.bitcoin.it/wiki/Thin_Client_Security">thin client</a>"
implementations to reduce required computing resources, the security
assumptions of the topology available to implementations of the DID
method MUST be discussed.
        </li>

        <li>
DID methods MUST discuss the policy mechanism by which DIDs are
proven to be uniquely assigned. A DID fits the functional definition
of a URN as defined in [[RFC8141]]—a persistent identifier that is
assigned once to a resource and never reassigned. In a security
context this is particularly important since a DID may be used to
identify a specific party subject to a specific set of authorization
rights.
        </li>

        <li>
DID methods that introduce new authentication service endpoint
types (Section <a href="#service-endpoints"></a>) SHOULD consider the
security requirements of the supported authentication protocol.
        </li>
      </ol>
    </section>

    <section>
      <h2>
Choosing DID Resolvers
      </h2>

      <p>
The [[DID-METHOD-REGISTRY]] is an informative list of DID method names
and their corresponding DID Method specifications.
Implementors should bear in mind that there is no central authority to
mandate which DID Method specification must be used with any particular
DID Method name, but can use the [[DID-METHOD-REGISTRY]] to make an
informed decision when choosing which <a href="#did-resolvers"></a>
implementations to use.
      </p>
    </section>

    <section>
      <h2>
Binding of Identity
      </h2>

      <section>
        <h3>
Proving Control of a DID and DID Document
        </h3>

        <p>
Signatures are one method to allow DID Documents to be
cryptographically verifiable.
        </p>

        <p>
By itself, a verified signature on a self-signed DID Document does
not prove control of a DID. It only proves the following:
        </p>

        <ol start="1">
          <li>
The DID Document has not been tampered with since it was
registered.
          </li>

          <li>
The controller of the DID Document controlled the private key used
for the signature at the time the signature was generated.
          </li>
        </ol>

        <p>
Proving control of a DID, i.e., the binding between the DID and
the DID Document that describes it, requires a two step process:
        </p>

        <ol start="1">
          <li>
Resolving the DID to a DID Document according to its DID method
specification.
          </li>

          <li>
Verifying that the id property of the resulting DID Document
matches the DID that was resolved.
          </li>
        </ol>

        <p>
It should be noted that this process proves control of a DID and
DID Document regardless of whether the DID Document is signed.
        </p>

        <p>
Signatures on DID Documents are optional. DID Method Specs SHOULD
explain and specify their implementation if applicable.
        </p>

        <p>
It is RECOMMENDED to combine timestamps with signatures.
        </p>
      </section>

      <section>
        <h3>
Proving Control of a Public Key
        </h3>

        <p>
There are two methods for proving control of the private key
corresponding to a public key description in the DID Document:
static and dynamic. The static method is to sign the DID Document
with the private key. This proves control of the private key at a
time no later than the DID Document was registered. If the DID
Document is not signed, control of a public key described in the
DID Document may still be proven dynamically as follows:
        </p>

        <ol start="1">
          <li>
Send a challenge message containing a public key description
from the DID Document and a nonce to an appropriate service
endpoint described in the DID Document.
          </li>

          <li>
Verify the signature of the response message against the public
key description.
          </li>
        </ol>
      </section>

      <section>
        <h3>
Authentication and Verifiable Claims
        </h3>

        <p>
A DID and DID Document do not inherently carry any
<a href="https://en.wikipedia.org/wiki/Personally_identifiable_information">
PII</a> (personally-identifiable information). The process of
binding a DID to something in the real-world such as a person or company,
for example with credentials with the same subject as that DID, is out
of scope for this specification. However this topic is the focus of the
<a href="https://w3c.github.io/vctf/">verifiable claims</a>
standardization work at the W3C (where the term "DID" originated).
        </p>
      </section>
    </section>

    <section>
      <h2>
Authentication Service Endpoints
      </h2>

      <p>
If a DID Document publishes a service endpoint intended for
authentication or authorization of the subject (section
<a href="#service-endpoints"></a>), it is the responsibility of the service
endpoint provider, subject, and/or relying party to comply with the
requirements of the authentication protocol(s) supported at that
service endpoint.
      </p>
    </section>

    <section>
      <h2>
Non-Repudiation
      </h2>

      <p>
Non-repudiation of DIDs and DID Document updates is supported under
the assumption that: (1) the subject is monitoring for unauthorized
updates (see Section <a href="#notification-of-did-document-changes"></a>)
and (2) the subject has had adequate opportunity to revert malicious updates
according to the DID method's access control mechanism (section
<a href="#authentication"></a>).
This capability is further supported if timestamps are included (sections
<a href="#created-optional"></a> and <a href="#updated-optional"></a>) and the
target DLT system supports timestamps.
      </p>
    </section>

    <section>
      <h2>
Notification of DID Document Changes
      </h2>

      <p>
One mitigation against unauthorized changes to a DID Document is
monitoring and actively notifying the subject when there are changes.
This is analogous to helping prevent account takeover on conventional
username/password accounts by sending password reset notifications to
the email addresses on file. In the case of a DID, where there is no
intermediary registrar or account provider to generate the
notification, the following approaches are RECOMMENDED:
      </p>

      <ol start="1">
        <li>
Subscriptions. If the <a>Decentralized Identifier Registry</a> on which the DID is
registered directly supports change notifications, this service can
be offered to DID controllers. Notifications may be sent directly to the
relevant service endpoints listed in an existing DID.
        </li>

        <li>
Self-monitoring. A DID subject may employ their own local or online
agent to periodically monitor for changes to a DID Document.
        </li>

        <li>
Third-party monitoring. A DID subject may rely on a third party
monitoring service, however this introduces another vector of attack.
        </li>
      </ol>
    </section>

    <section>
      <h2>
Key and Signature Expiration
      </h2>

      <p>
In a decentralized identifier architecture, there are no centralized
authorities to enforce key or signature expiration policies.
Therefore DID resolvers and other client applications SHOULD validate
that keys were not expired at the time they were used. Since some use cases
may have legitimate reasons why already-expired keys can be extended, a key
expiration SHOULD NOT prevent any further use of the key, and implementations
of a resolver SHOULD be compatible with such extension behavior.
      </p>
    </section>

    <section>
      <h2>
Key Revocation and Recovery
      </h2>

      <p>
Section <a href="#did-operations"></a> specifies the DID operations
that must be supported by a DID method specification, including
deactivation of a DID Document by replacing it with an updated DID
Document. In general, checking for key revocation on DLT-based
methods is expected to be handled in a manner similar to checking the
balance of a cryptocurrency account on a distributed ledger: if the
balance is empty, the entire DID is deactivated. DID method
specifications SHOULD enable support for a quorum of trusted parties
to enable key recovery. Some of the facilities to do so are suggested
in section 6.5, Authorization. Note that not all DID method
specifications will recognize control from DIDs registered using
other DID methods and they MAY restrict third-party control to DIDs
that use the same method. Access control and key recovery in a DID
method specification MAY also include a time lock feature to protect
against key compromise by maintaining a second track of control for
recovery. Further specification of this type of control is a matter
for future work (see Section <a href="#time-locks-and-did-document-recovery"></a>).
      </p>
    </section>

    <section>
      <h2>
The Role of Human-Friendly Identifiers
      </h2>

      <p>
DIDs achieve global uniqueness without the need for a central
registration authority. This comes, however, at the cost of human
memorability. The algorithms capable of generating globally unique
identifiers automatically produce random strings of characters that
have no human meaning. This demonstrates the axiom about
identifiers known as <a href="https://en.wikipedia.org/wiki/Zooko%27s_triangle">Zooko's
Triangle</a>: "human-meaningful, decentralized, secure—pick any
two".
      </p>

      <p>
There are of course many use cases where it is desirable to
discover a DID when starting from a human-friendly identifier—a
natural language name, a domain name, or a conventional address for
a DID controller such as a mobile telephone number, email address,
Twitter handle, or blog URL. However, the problem of mapping
human-friendly identifiers to DIDs (and doing so in a way that can
be verified and trusted) is out-of-scope for this specification.
      </p>

      <p>
Solutions to this problem (and there are many) should be defined in
separate specifications that reference this specification. It is
strongly recommended that such specifications carefully consider:
          (a) the numerous security attacks based on deceiving users about
the true human-friendly identifier for a target entity, and (b) the
privacy consequences of using human-friendly identifiers that are
inherently correlatable, especially if they are globally unique.
      </p>
    </section>

  </section>

  <section class="informative">
    <h1>
Privacy Considerations
    </h1>

    <p>
It is critically important to apply the principles of Privacy by Design
to all aspects of decentralized identifier architecture, because DIDs
and DID Documents are—by design—administered directly by their controllers.
There is no registrar, hosting company, or other intermediate service
provider to recommend or apply additional privacy safeguards. The
authors of this specification have applied all seven Privacy by Design
principles throughout its development. For example, privacy in this
specification is preventative not remedial, and privacy is an embedded
default. Furthermore, decentralized identifier architecture by itself
embodies principle #7, "Respect for user privacy—keep it user-centric."
This section lists additional privacy considerations that implementers,
delegates, and DID subjects should bear in mind.
    </p>

    <section>
      <h2>
Requirements of DID Method Specifications
      </h2>

      <ol start="1">
        <li>
DID method specifications MUST include their own Privacy
Considerations sections, if only to point to the general privacy
considerations in this section.
        </li>

        <li>
The DID method privacy section MUST discuss any subsection of
section 5 of [[RFC6973]] that could apply in a method-specific
manner. The subsections to consider are: surveillance, stored data
compromise, unsolicited traffic, misattribution, correlation,
identification, secondary use, disclosure, exclusion.
        </li>
      </ol>
    </section>

    <section>
      <h2>
Keep Personally-Identifiable Information (PII) Private
      </h2>

      <p>
If a DID method specification is written for a public <a>Decentralized
Identifier Registry</a> where all DIDs and DID Documents will be publicly available,
it is STRONGLY RECOMMENDED that DID Documents contain no PII. All PII
should be kept behind service endpoints under the control
of the subject. With this privacy architecture, PII may be exchanged
on a private, peer-to-peer basis using communications channels
identified and secured by key descriptions in DID documents. This also
enables subjects and relying parties to implement the
<a href="https://en.wikipedia.org/wiki/General_Data_Protection_Regulation">GDPR</a>
<a href="https://en.wikipedia.org/wiki/Right_to_be_forgotten">right
to be forgotten</a>, as no PII will be written to an immutable
ledger.
      </p>
    </section>

    <section>
      <h2>
DID Correlation Risks and Pseudonymous DIDs
      </h2>

      <p>
Like any type of globally unique identifier, DIDs may be used for
correlation. DID controllers can mitigate this privacy risk by using
pairwise unique DIDs, i.e., by sharing a different private DID for
every relationship. In effect, each DID acts as a pseudonym. A
pseudonymous DID need only be shared with more than one party when
the subject explicitly authorizes correlation between those parties.
If pseudonymous DIDs are the default, then the only need for a public
DID—a DID published openly or shared with a large number of
parties—is when the subject explicitly desires public identification.
      </p>
    </section>

    <section>
      <h2>
DID Document Correlation Risks
      </h2>

      <p>
The anti-correlation protections of pseudonymous DIDs are easily
defeated if the data in the corresponding DID Documents can be
correlated. For example, using same public key descriptions or
bespoke service endpoints in multiple DID Documents can provide as
much correlation information as using the same DID. Therefore the DID
Document for a pseudonymous DID SHOULD also use pairwise-unique
public keys.

It might seem natural to also use pairwise-unique service endpoints
in the DID Document for a pseudonymous DID. However, unique endpoints
allow all traffic between to DIDs to be isolated perfectly into
unique buckets, where timing correlation and similar analysis is easy.
Therefore, a better strategy for endpoint privacy may be to share an
endpoint among thousands or millions of DIDs controlled by many different
subjects.
      </p>
    </section>

    <section>
      <h2>
Herd Privacy
      </h2>

      <p>
When a DID subject is indistinguishable from others in the herd, privacy
is available. When the act of engaging privately with another party
is by itself a recognizable flag, privacy is greatly diminished. DIDs
and DID methods SHOULD work to improve herd privacy, particularly for
those who legitimately need it most. Choose technologies and human
interfaces that default to preserving anonymity and pseudonymity. In
order to reduce <a href="https://en.wikipedia.org/wiki/Device_fingerprint">digital
fingerprints</a>, share common settings across client
implementations, keep negotiated options to a minimum on wire
protocols, use encrypted transport layers, and pad messages to
standard lengths.
      </p>
    </section>
  </section>

  <section class="informative">
    <h1>
Future Work
    </h1>

    <section>
      <h2>
Upper Limits on DID Character Length
      </h2>

      <p>
The current specification does not take a position on maximum length
of a DID. The maximum interoperable URL length is currently about 2K
characters. QR codes can handle about 4K characters. Clients using
DIDs will be responsible for storing many DIDs, and some methods
would be able to externalize some of their costs onto clients by
relying on more complicated signature schemes or by adding state into
DIDs intended for temporary use. A future version of this
specification should set reasonable limits on DID character length to
minimize externalities.
      </p>
    </section>

    <section>
      <h2>
Equivalence
      </h2>

      <p>
Including an equivalence property, such as equivID, in DID Documents
whose value is an array of DIDs would allow subjects to assert two or
more DIDs that represent the same subject. This capability has
numerous uses, including supporting migration between <a>Decentralized
Identifier Registries</a> and
providing forward compatibility of existing DIDs to future <a>Decentralized
Identifier Registries</a>. In
theory, equivalent DIDs should have the same identifier rights,
allowing <a href="https://w3c.github.io/vctf/">verifiable claims</a>
made against one DID to apply to equivalent DIDs. Equivalence was not
included in the current specification due to the complexity of
verifying equivalence across different DLTs and different DID
methods, and also of aggregating properties of equivalent DID
Documents. However equivalence should be supported in a future
version of this specification.
      </p>
    </section>

    <section>
      <h2>
Timestamps
      </h2>

      <p>
Verifiable timestamps have significant utility for identifier
records. This is a good fit for DLTs, since most offer some type of
timestamp mechanism. Despite some transactional cost, they are the
most censorship-resistant transaction ordering systems in the world,
so they are nearly ideal for DID Document timestamping. In some cases
a DLT's immediate timing is approximate, however their sense of
<a href="https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki%23Abstract">
        "median time past" (see Bitcoin BIP 113)</a> can be precisely
defined. A generic DID Document timestamping mechanism could would
work across all DLTs and might operate via a mechanism including
either individual transactions or transaction batches. The generic
mechanism was deemed out of scope for this version, although it may
be included in a future version of this specification.
      </p>
    </section>

    <section>
      <h2>
Time Locks and DID Document Recovery
      </h2>

      <p>
Section <a href="#key-revocation-and-recovery"></a> mentions one
possible clever use of time locks to recover control of a DID after a
key compromise. The technique relies on an ability to override the
most recent update to a DID Document with Authorization applied by an
earlier version of the DID Document in order to defeat the attacker.
This protection depends on adding a <a href="https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki%23Abstract">
time lock (see Bitcoin BIP 65)</a> to protect part of the transaction
chain, enabling a Authorization block to be used to recover control.
We plan to add support for time locks in a future version of this
specification.
      </p>
    </section>

    <section>
      <h2>
Smart Signatures
      </h2>

      <p>
Not all DLTs can support the Authorization logic in section 6.5.
Therefore, in this version of the specification, all Authorization
logic must be delegated to DID method specifications. A potential
future solution is a <a href="http://www.weboftrust.info/downloads/smart-signatures.pdf">Smart
Signature</a> specification that specifies the code any conformant
DLT may implement to process signature control logic.
      </p>
    </section>

    <section>
      <h2>
Verifiable Claims
      </h2>

      <p>
Although DIDs and DID Documents form a foundation for decentralized
identity, they are only the first step in describing their subjects. The
rest of the descriptive power comes through collecting and
selectively using <a href="https://w3c.github.io/vctf/">verifiable
claims</a>. Future versions of the specification will describe in
more detail how DIDs and DID Document can be integrated with—and help
enable—the verifiable claims ecosystem.
      </p>
    </section>

    <section>
      <h2>
Alternate Serializations and Graph Models
      </h2>

      <p>
This version of the specification relies on JSON-LD and the RDF graph
model for expressing a DID Document. Future versions of this
specification MAY specify other semantic graph formats for a DID
Document, such as JXD (JSON XDI Data), a serialization format for the
XDI graph model as defined by the <a href="http://docs.oasis-open.org/xdi/xdi-core/v1.0/csd01/xdi-core-v1.0-csd01.xml">
OASIS XDI Core 1.0 specification</a>.
      </p>
    </section>
  </section>

  <section class="appendix">
    <h1>
Registries
    </h1>

    <p>
There are multiple registries that define DID Methods and extensions to
this specification. These registries are:
    </p>

    <table class="simple">
      <thead>
        <tr>
          <th>
Registry
          </th>
          <th>
Purpose
          </th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
<a href="https://w3c-ccg.github.io/did-method-registry/">DID
Method Registry</a>
          </td>
          <td>
Lists all known DID Methods and contains links to their
specifications.
          </td>
        </tr>

        <tr>
          <td>
<a href="https://w3c-ccg.github.io/ld-cryptosuite-registry/">Linked Data
Cryptography Suite Registry</a>
          </td>
          <td>
Defines all known Linked Data Cryptography Suites and Key
Formats.
          </td>
        </tr>
      </tbody>
    </table>
  </section>

  <section class="appendix">
    <h1>
Real World Example
    </h1>

    <p>
A future-facing real-world context is provided below:
    </p>

    <pre class="example nohighlight" title="Advanced DID Document example">
{
  "@context": "https://w3id.org/future-method/v1",
  "id": "did:example:123456789abcdefghi",

  "publicKey": [{
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }, {
    "id": "did:example:123456789abcdefghi#keys-3",
    "type": "Ieee2410VerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],

  "authentication": [
    // this mechanism can be used to authenticate as did:...fghi
    "did:example:123456789abcdefghi#keys-1",
    // this mechanism can be used to biometrically authenticate as did:...fghi
    "did:example:123456789abcdefghi#keys-3",
    // this mechanism is *only* authorized for authentication, it may not
    // be used for any other proof purpose, so its full description is
    // embedded here rather than using only a reference
    {
      "id": "did:example:123456789abcdefghi#keys-2",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:example:123456789abcdefghi",
      "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],

  "service": [{
    "id": "did:example:123456789abcdefghi#oidc",
    "type": "OpenIdConnectVersion1.0Service",
    "serviceEndpoint": "https://openid.example.com/"
  }, {
    "id": "did:example:123456789abcdefghi#vcStore",
    "type": "CredentialRepositoryService",
    "serviceEndpoint": "https://repository.example.com/service/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#xdi",
    "type": "XdiService",
    "serviceEndpoint": "https://xdi.example.com/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#hub",
    "type": "HubService",
    "serviceEndpoint": "https://hub.example.com/.identity/did:example:0123456789abcdef/"
  }, {
    "id": "did:example:123456789abcdefghi#messaging",
    "type": "MessagingService",
    "serviceEndpoint": "https://example.com/messages/8377464"
  }, {
    "type": "SocialWebInboxService",
    "id": "did:example:123456789abcdefghi#inbox",
    "serviceEndpoint": "https://social.example.com/83hfh37dj",
    "description": "My public social inbox",
    "spamCost": {
      "amount": "0.50",
      "currency": "USD"
    }
  }, {
    "type": "DidAuthPushModeVersion1",
    "id": "did:example:123456789abcdefghi#push",
    "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefghi"
  }, {
    "id": "did:example:123456789abcdefghi#bops",
    "type": "BopsService",
    "serviceEndpoint": "https://bops.example.com/enterprise/"
  }]
}
</pre>
  </section>

</body>
</html>
